\documentclass[12pt]{article}

\usepackage{hyperref}

\setlength{\oddsidemargin}{0in}
\setlength{\evensidemargin}{0in}
\setlength{\textwidth}{6.5in}
\setlength{\textheight}{8.5in}
\setlength{\topmargin}{-0.5in}
\setlength{\parindent}{0.5in}

\newcommand{\despotic}{\texttt{DESPOTIC}}

\begin{document}

\title{User's Guide for \despotic\ v.~1.1.0}
\author{Mark Krumholz}

\maketitle

\tableofcontents

\clearpage

\section{License and Citations}

This is a guide for users of the \despotic\ software package. \despotic\ is distributed under the terms of the \href{http://http://www.gnu.org/licenses/gpl.html}{GNU General Public License v.~3}. A copy of the license notification is included in all the source files.

If you use \despotic\ in any published work, please cite the paper Krumholz, M.~R., 2013, ``\despotic\ -- A New Software Library to Derive the Energetics and SPectra of Optically Thick Interstellar Clouds", submitted to \textit{Monthly Notices of the Royal Astronomical Society}, \href{http://arxiv.org/abs/1304.2404}{arXiv:1304.2404}.

In addition, if you make use of any of \despotic's capabilities that take advantage of data from the \href{http://home.strw.leidenuniv.nl/~moldata/}{Leiden Atomic and Molecular Database}, please cite Sch\"oier, F.~L., van der Tak, F.~F.~S., van Dishoeck, E.~F., and Black, J.~H., 2005, ``An atomic and molecular database for analysis of submillimetre line observations", \textit{Astronomy \& Astrophysics}, 432, 369, and please cite the individual data sources for particular LAMDA files. These sources may be found at the \href{http://home.strw.leidenuniv.nl/~moldata/}{LAMDA website}.

\clearpage


\section{Installation}

This section describes several options for how to get \despotic.

\subsection{Downloading from Google Code}

To download the full \despotic\ distribution, just type

\begin{verbatim}
svn checkout http://despotic.googlecode.com/svn/trunk/ despotic-read-only
\end{verbatim}

This will create a directory \verb=despotic=, which will contain the subdirectories \verb=cloudfiles=, \verb=despotic=, \verb=dist=, \verb=doc=, and \verb=examples=. The \despotic\ package is in the \verb=despotic= directory, while the other directories contain sample cloud files, a distribution that can be installed as a site package, this User's Guide, and some example Python scripts that use \despotic.

At this point you can start using \despotic\ immediately, but you might want to either set the environment variable \verb=$PYTHONPATH= to the \verb=despotic= subdirectory, or you might want to install \despotic\ as a site package. If you do neither of these, you will only be able to run \despotic\ when you are in the directory you just downloaded.

To install \despotic\ as a site package, simply cd into the \verb=despotic= subdirectory and type
\begin{verbatim}
python setup.py install
\end{verbatim}
Depending on how your python installation is configured, you may need to prepend the command above with \verb=sudo=.

\subsection{Downloading from the Python Package Index}

You can also download and the \despotic\ package from the Python Package Index, at \url{https://pypi.python.org/pypi/DESPOTIC/}. This distribution includes only the \despotic\ source, not any of the documentation or example files. The easiest way to install from PPI is using pip, the Python Installer Package. If you have pip installed, you can download \despotic\ simply by typing
\begin{verbatim}
pip install despotic
\end{verbatim}
Depending on how your python installation is configured, you may need to prepend the command above with \verb=sudo=.


\subsection{Specifying the Location of LAMDA}

\despotic\ uses the environment variable \verb=$DESPOTIC_HOME= as a location where the locally-cached version of the Leiden Atomic and Molecular Database (LAMDA) should be located (see Section \ref{sec:lamda}). It is recommended that you set this environment variable to the directory containing the \despotic\ distribution you just downloaded. However, this is not required. If this environment variable is not set, \despotic\ will just use the current working directory to store LAMDA files unless you tell it otherwise.


\subsection{Requirements and Dependencies}

\despotic\ requires \verb;sciPy >= 0.11.0;.

\clearpage

\section{Quickstart Example}

As with any Python program, \despotic\ can be used either interactively or non-interactively. For the purposes of the Quickstart we will assume the commands are being issued in interactive mode, but they will work equally well non-interactively.

The basic object in \despotic, which provides an interface to most of its functionality, is the class \texttt{cloud}. This class stores the basic properties of an interstellar cloud, and provides methods to perform calculations on those properties. The first step in most \despotic\ sessions is to import this class:
\begin{verbatim}
from despotic import cloud
\end{verbatim}
This command puts the cloud class into the current namespace.

The next step is generally to input data describing a cloud upon which computations are to be performed. The input data describe the cloud's physical properties (density, temperature, etc.), the bulk composition of the cloud, what emitting species it contains, and the radiation field around it. While it is possible to enter the data manually, it is usually easier to read the data from a \despotic\ cloud file. The format for these files is described in Section \ref{sec:cloudfiles}. For this Quickstart, we'll use one of the configuration files that ship with \despotic\, and that are included in the cloudfiles subdirectory of the \despotic\ distribution. To create a cloud whose properties are as given in a particular cloud file, we simply invoke the constructor with the fileName optional argument set equal to a string containing the name of the file to be read:
\begin{verbatim}
gmc = cloud(fileName='cloudfiles/MilkyWayGMC.desp', verbose=True)
\end{verbatim}
Note the optional argument verbose, which we have set to True. Most \despotic\ methods accept the verbose argument, which causes them to produce printed output containing a variety of information. In this case, the  By default \despotic\ operations are silent.

At this point most of the calculations one could want to do on a cloud are provided as methods of the cloud class. One of the most basic is to set the cloud to its equilibrium dust and gas temperatures. This is accomplished via the setTempEq method:
\begin{verbatim}
gmc.setTempEq(verbose=True)
\end{verbatim}
With verbose set to True, this command will produce variety of output as it iterates to calculate the equilibrium gas and dust temperatures, before finally printing True. This illustrates another feature of \despotic\ commands: those that iterate return a value of True if they converge, and False if they do not.

To see the gas and dust temperatures to which the cloud has been set, we can simply print them:
\begin{verbatim}
print gmc.Tg
print gmc.Td
\end{verbatim}
This shows that \despotic\ has calculated an equilibrium gas temperature of $10.2$ K, and an equilibrium dust temperature of $14.4$ K.

Next we might wish to compute the CO line emission emerging from the cloud. We do this with the cloud method lineLum:
\begin{verbatim}
lines = gmc.lineLum('co')
\end{verbatim}
The argument 'co' specifies that we are interested in the emission from the CO molecule. This method returns a list of dicts, each of which gives information about one of the CO lines. The dict contains a variety of fields, but one of them is the velocity-integrated brightness temperature of the line. Again, we can just print the values we want. The first element in the list is the $J=1-0$ line, and the velocity-integrated brightness temperature is listed as intTB in the dict. Thus to get the velocity-integrated brightness temperature of the first line, we just do
\begin{verbatim}
print lines[0]['intTB']
\end{verbatim}
This shows that the velocity-integrated brightness temperature of the CO $J=1-0$ line is 79 K km s$^{-1}$.

Finally, we might wish to know the heating and cooling rates produced by various processes, which lets us determined what sets the thermal balance in the cloud. This may be computed using the method dEdt, as follows:
\begin{verbatim}
rates = gmc.dEdt()
\end{verbatim}
This method returns a dict that contains all the heating and cooling terms for gas and dust. For example, we can print the rates of cosmic ray heating and CO line cooling via
\begin{verbatim}
print rates['GammaCR']
print rates['LambdaLine']['co']
\end{verbatim}

\clearpage

\section{Functional Guide to \despotic\ Capabilities}

This section covers the most common tasks for which \despotic\ can be used. They are not intended to provide a comprehensive overview of the library's capabilities, and users who wish to understand every available option should refer to Section \ref{sec:full}. The routines used in this section are all described in full detail there. For all of these operations, the user should first have imported the basic \despotic\ class \verb=cloud= by doing
\begin{verbatim}
from despotic import cloud
\end{verbatim}


\subsection{Computing Line Emission}

The most basic task in \despotic\ is computing the line emission emerging from a cloud of specified physical properties. The first step in any computation of line emission is to create a \verb=cloud= object with the desired properties. This is often most easily done by creating a \despotic\ cloud file following the directions in Section \ref{sec:cloudfiles}, but the user can also create a cloud with the desired properties manually. The properties that are important for line emission are the gas volume density, column density, temperature, velocity dispersion, and chemical composition; these are stored in the \verb=cloud= class and the composition class within it. For example, the following code snippet
\begin{verbatim}
mycloud = cloud()
mycloud.nH = 1.0e2
mycloud.colDen = 1.0e22
mycloud.sigmaNT = 2.0e5
mycloud.Tg = 10.0
mycloud.comp.xoH2 = 0.1
mycloud.comp.xpH2 = 0.4
mycloud.comp.xHe = 0.1
\end{verbatim}
creates a cloud with all its parameters set to default values, a volume density of $n_{\rm H} = 10^2$ cm$^{-3}$, a column density of $N_{\rm H} = 10^{22}$ cm$^{-2}$, a non-thermal velocity dispersion of $\sigma_{\rm NT} = 2.0\times 10^5$ cm s$^{-1}$, a gas temperature of $T_g = 10$ K, and a composition that is $0.1$ ortho-H$_2$ molecules per H nucleus, 0.4 para-H$_2$ molecules, and $0.1$ He atoms per H nucleus.

The next step is to specify the emitting species whose line emission is to be computed. As with the physical properties of the cloud, this is often most easily done by creating a cloud file. However, it can also be done manually by using the \verb=cloud.addEmitter= method, which allows users to add emitting species to clouds. The following code snippet adds CO as an emitting species, at an abundance of $10^{-4}$ CO molecules per H nucleus:
\begin{verbatim}
mycloud.addEmitter('CO', 1.0e-4)
\end{verbatim}
The first argument is the name of the emitting species, and the second is the abundance. The requisite molecular data file will be read from disk if it is available, or automatically downloaded from the Leiden Atomic and Molecular Database if it is not.

Once an emitter has been added, only a single call is required to calculate the luminosity of its lines:
\begin{verbatim}
lines = mycloud.lineLum('CO')
\end{verbatim}
The argument is just the name of the species whose line emission should be computed. Note that it must match the name of an existing emitter, and that emitter names are case-sensitive. The value returned by this procedure, which is stored in the variable \verb=ilnes=, is a sequence of Python dicts, with each dict describing the properties of a single line. Lines are ordered by frequency, from lowest to highest. Each dict contains the following keys-value pairs: \verb=freq= is the line frequency in Hz, \verb=intIntensity= is the frequency-integrated intensity of the line after subtracting off the CMB contribution, in erg cm$^{-2}$ s$^{-1}$ sr$^{-1}$, \verb=intTB= is the velocity-integrated brightness temperature (again subtracting off the CMB) in K km s$^{-1}$, and \verb=lumPerH= is the rate of energy emission in the line per H nucleus in the cloud, in erg s$^{-1}$. This is a partial list of what the dict contains; see Section \ref{sec:linelum} for a full listing.

Once the data have been obtained, the user can do what he or she wishes with them. For example, to plot velocity-integrated brightness temperature versus line frequency, the user might do
\begin{verbatim}
freq = [l['freq'] for l in lines]
TB = [l['intTB'] for l in lines]
plot(freq, TB, 'o')
\end{verbatim}

\subsection{Computing Heating and Cooling Rates}

To use \despotic's capability to calculate heating and cooling rates, in addition to the quantities specified for a calculation of line emission one must also add the quantities describing the dust and the radiation field. As before, this is most easily accomplished by creating a \despotic\ cloud file containing the requisite information (Section \ref{sec:cloudfiles}), but the data can also be input manually. The code snippet below does so:
\begin{verbatim}
mycloud.dust.alphaGD   = 3.2e-34    # Dust-gas coupling coefficient
mycloud.dust.sigma10   = 2.0e-25    # Cross section for 10K thermal radiation
mycloud.dust.sigmaPE   = 1.0e-21    # Cross section for photoelectric heating
mycloud.dust.sigmaISRF = 3.0e-22    # Cross section to the ISRF
mycloud.dust.beta      = 2.0        # Dust spectral index
mycloud.dust.Zd        = 1.0        # Abundance relative to Milky Way
mycloud.Td             = 10.0       # Dust temperature
mycloud.rad.TCMB       = 2.73       # CMB temperature
mycloud.rad.TradDust   = 0.0        # IR radiation field seen by the dust
mycloud.rad.ionRate    = 2.0e-17    # Primary ionization rate
mycloud.rad.chi        = 1.0        # ISRF normalized to Solar neighborhood
\end{verbatim}
These quantities, all in CGS units, specify the dust-gas coupling constant, the dust cross section to 10 K thermal radiation, the dust cross section to the $8-13.6$ eV photons the dominate photoelectric heating, the dust cross section to the broader interstellar radiation field responsible for heating the dust, the dust spectral index, the dust abundance relative to the Milky Way value, the dust temperature, the cosmic microwave background temperature, the infrared radiation field that heats the dust, the primary ionization rate due to cosmic rays and x-rays, and the ISRF strength normalized to the Solar neighborhood value. All of the numerical values shown in the code snippet above are in fact the defaults, and so none of the above commands are strictly necessary. However, it is generally wise to set quantities explicitly rather than relying on default values.

Once these data have been input, one may compute all the heating and cooling terms that \despotic\ includes using the \verb=cloud.dEdt= routine:
\begin{verbatim}
rates = mycloud.dEdt()
\end{verbatim}
This call returns a dict which contains the instantaneous rates of heating and cooling, all in erg s$^{-1}$ H$^{-1}$. The entries in the dict are: \verb=GammaPE=, the gas photoelectric heating rate, \verb=GammaCR=, the gas heating rate due to cosmic ray and X-ray ionization, \verb=GammaGrav=, the gas heating rate due to gravitational compression, \verb=GammaDustISRF=, the dust heating rate due to the ISRF, \verb=GammaDustCMB=, the dust heating rate due to the CMB, \verb=GammaDustIR=, the dust heating rate due to the IR field, \verb=GammaDustLine=, the dust heating rate due to absorption of line photons, \verb=PsiGD=, the gas-dust energy exchange rate (positive means gas heating, dust cooling), \verb=LambdaDust=, the dust cooling rate via thermal emission, and \verb=LambdaLine=, the gas cooling rate via line emission. This last quantity is itself a dict, with one entry per emitting species and the dictionary keys corresponding to the emitter names. Thus in the above example, one could see the cooling rate via CO emission by doing
\begin{verbatim}
print rates['LambdaLine']['CO']
\end{verbatim}


\subsection{Computing Temperature Equilibria}

Computing the equilibrium temperature requires exactly the same quantities as computing the heating and cooling rates; indeed, the process of computing the equilibrium temperature simply amounts to searching for values of $T_g$ and $T_d$ such that the sum of the heating and cooling rates returned by \verb=cloud.dEdt= are zero. One may perform this calculation using the \verb=cloud.setTempEq= method:
\begin{verbatim}
mycloud.setTempEq()
\end{verbatim}
This routine iterates to find the equilibrium gas and dust temperatures, and returns True if the iteration converges. After this call, the computed dust and gas temperatures may simply be read off:
\begin{verbatim}
print mycloud.Td, mycloud.Tg
\end{verbatim}

The \verb=cloud.setTempEq= routine determines the dust and gas temperatures simultaneously. However, there are many situations where it is preferable to solve for only one of these two, while leaving the other fixed. This may be accomplished by the calls
\begin{verbatim}
mycloud.setDustTempEq()
mycloud.setGasTempEq()
\end{verbatim}
These routines, respectively, set \verb=mycloud.Td= while leaving \verb=mycloud.Tg= fixed, or vice-versa. Solving for one temperature at a time is often faster, and if dust-gas coupling is known to be negligible will produce nearly identical results as solving for the two together.


\subsection{Computing Time-Dependent Thermal Evolution}

To perform computations of time-dependent temperature evolution, \despotic\ provides the method \verb=cloud.tempEvol=. In its most basic form, this routine simply accepts an argument specifying the amount of time for which the cloud is to be integrated, and returning the temperature as a function of time during this evolution:
\begin{verbatim}
mycloud.Tg = 50.0         # Start the cloud out of equilibrium
tFinal = 20 * 3.16e10     # 20 kyr
Tg, t = mycloud.tempEvol(tFinal)
\end{verbatim}
The two values returned are arrays, the second of which gives a series of 100 equally-spaced times between 0 and \verb=tFinal=, and the first of which gives the temperatures at those times. The number of output times, the spacing between them, and their exact values may all be controlled by optional arguments -- see Section \ref{sec:tempevol} for details. At the end of this evolution, the cloud temperature \verb=mycloud.Tg= will be changed to its value at the end of 20 kyr of evolution, and the dust temperature \verb=mycloud.Tg= will be set to its thermal equilibrium value at that cloud temperature.

If one wishes to examine the intermediate states in more detail, one may also request that the full state of the cloud be saved at every time:
\begin{verbatim}
clouds, t = mycloud.tempEvol(tFinal, fullOutput=True)
\end{verbatim}
The \verb=fullOutput= optional argument, if True, causes the routine to return a full copy of the state of the cloud at each output time, instead of just the gas temperature \verb=Tg=. In this case, \verb=clouds= is a sequence of 100 clouds, and one may interrogate their states (e.g.~calculating their line emission) using the usual routines.


\subsection{Computing Chemical Equilibria}

As of version 1.1.0, \despotic\ can also compute the chemical abundances in clouds using chemistry networks. There are a vast number of possible chemical networks, but at present \despotic\ only includes the reduced carbon-oxygen chemistry network of Nelson \& Langer (1999, \textit{Astrophysical Journal}, 524, 923), which computes most of the important reactions involving carbon and oxygen. (\despotic\ provides a generic chemical network class and drivers so that it is straightforward to expand to include other chemical networks; see Section \ref{sec:chem}.)

To perform computations with this network, one must first import the class that defines it:
\begin{verbatim}
from despotic.chemistry import NL99
\end{verbatim}
One can set the equilibrium abundances of a cloud to the equilibrium values determined by the network via the command
\begin{verbatim}
mycloud.setChemEq(network=NL99)
\end{verbatim}
The argument \verb=network= specifies that the calculation should use the \verb=NL99= class. This call sets the abundances of all the emitters that are included in the network to their equilibrium values. In this case, the network includes CO, and thus it sets the CO abundance to a new value:
\begin{verbatim}
print mycloud.emitters['CO'].abundance
\end{verbatim}

One can also see the abundances of all the species included in the network, including those that do not correspond to emitters in the cloud, by printing the chemical network property \verb=abundances=:
\begin{verbatim}
print mycloud.chemnetwork.abundances
\end{verbatim}
Once the chemical network is associated with the cloud, subsequent calls to \verb=setChemEq= need not include the \verb=network= keyword. \despotic\ assumes that all subsequent chemical calculations are to be performed with the same chemical network unless it is explicitly told otherwise via a call to \verb=setChemEq= or \verb=chemEvol= (see the next section) that specifies a different chemical network.

\subsection{Computing Time-Dependent Chemical Evolution}

\despotic\ can also calculate time-dependent chemical evolution. This is accomplished through the method \verb=cloud.chemEvol=.  At with \verb=cloud.tempEvol=, this routine accepts an argument specifying the amount of time for which the cloud is to be integrated, and returning the chemical abundances as a function of time during this evolution:
\begin{verbatim}
mycloud.rad.ionRate = 2.0e-16     # Raise the ionization rate a lot
tFinal = 0.5 * 3.16e13            # 0.5 Myr
abd, t = mycloud.chemEvol(tFinal)
\end{verbatim}
Note that the chemical network is not specified here, which is fine assuming that one has previously executed the \verb+mycloud.setChemEq(network=NL99)+ statement in the previous section, which assigns the NL99 network to the cloud. If one has not executed that statement, then the keyword \verb+network=NL99+ must be added to the call to \verb=mycloud.chemEvol=.

The output quantity \verb=abd= here is an object of class \verb=abundanceDict=, which is a specialized dict for handling chemical abundances. One can examine the abundances of specific species just by giving their chemical names. For example, to see the time-dependent evolution of the abundances of CO, C, and C$^+$, one could do
\begin{verbatim}
plot(t, abd['CO'])
plot(t, abd['C'])
plot(t, abd['C+'])
\end{verbatim}
As with \verb=setChemEq=, this routine modifies the abundances of emitters in the cloud to the values they achieve at the end of the evolution, so to see the final CO abundance one could do
\begin{verbatim}
print mycloud.emitters['CO'].abundance
\end{verbatim}


\subsection{Computing Line Profiles}

Line profile computation operates somewhat differently then the previous examples, because it is provided through a stand-alone procedure rather than through the \verb=cloud= class. This procedure is called \verb=lineProfLTE=, and may be imported directly from the \despotic\ package. The routine also requires emitter data stored in an \verb=emitterData= object. The first step in a line profile calculation is therefore to import these two objects into the Python environment:
\begin{verbatim}
from despotic import lineProfLTE
from despotic import emitterData
\end{verbatim}

The second step is to read in the emitter data. The interface to read emitter data is essentially identical to the one used to add an emitter to a cloud. One simply declares an \verb=emitterData= object, giving the name of the emitter as an argument:
\begin{verbatim}
csData = emitterData('CS')    # Reads emitter data for the CS molecule
\end{verbatim}
Alternately, emitter data may be obtained from a cloud, since clouds store emitter data for all their emitters. Using the examples from the previous sections,
\begin{verbatim}
coData = mycloud.emitters['CO'].data
\end{verbatim}
copies the emitter data for CO to the variable co.

The third step is to specify the radius of the cloud, and the profiles of any quantities within the cloud that are to change with radius, including density, temperature, radial velocity, and non-thermal velocity dispersion. Each of these can be constant, but the most interesting applications are when one or more of them are not, in which case they must be defined by functions. These function each take a single argument, the radius in units where the outer radius of the cloud is unity, and return a single floating point value, giving the quantity in question in CGS units. For example, to compute line profiles through a cloud of spatially-varying temperature and infall velocity, one might define the functions
\begin{verbatim}
R = 0.02 * 3.09e18    # 0.2 pc

def TProf(r):
    return 8.0 + 12.0*exp(-r**2/(2.0*0.5**2))

def vProf(r):
    return -4.0e4*r
\end{verbatim}
The first function sets a temperature that varies from 20 K in the center of close to 8 K at the outer edge, and the second defines a velocity that varies from 0 in the center to $-0.4$ km s$^{-1}$ (where negative indicates infall) at the outer edge. Similar functions can be defined by density and non-thermal velocity dispersion if the user so desires. Alternately, the user can simply define them as constants
\begin{verbatim}
ncs = 0.1         # CS density 0.1 cm^-3
sigmaNT = 2.0e4   # Non-thermal velocity dispersion 0.2 km s^-1
\end{verbatim}

The final step is to use the \verb=lineProfLTE= routine to compute the brightness temperature versus velocity:
\begin{verbatim}
TB, v = lineProfLTE(cs, 2, 1, R, ncs, TProf, vProf, sigmaNT).
\end{verbatim}
Here the first argument is the emitter data, the second and third are the upper and lower quantum states between which the line is to be computed (ordered by energy), followed by the cloud radius, the volume density, the temperature, the velocity, and the non-thermal velocity dispersion. Each of these quantities can be either a float or a callable function of one variable, as in the example above. If it is a float, that quantity is taken to be constant, independent of radius. This routine returns two arrays, the first of which is the brightness temperature and the second of which is the velocity at which that brightness temperature is computed, relative to line center. These can be examined in any of the usual \verb=numPy= ways, for example by plotting them:
\begin{verbatim}
plot(v, TB)
\end{verbatim}

By default the velocity is sampled at 100 values. The routine attempts to guess a reasonable range of velocities based on the input values of radial velocity and velocity dispersion, but these defaults may be overridden by the optional argument \verb=vLim=, which is a sequence of two values giving the lower and upper limits on the velocity:
\begin{verbatim}
TB, v = lineProfLTE(cs, 2, 1, R, ncs, TProf, vProf, sigmaNT, \
                    vLim=[-2e5,2e5]).
\end{verbatim}
A variety of other optional arguments can be used to control the velocities at which the brightness temperature is computed. It is also possible to compute line profiles at positions offset from the geometric center of the cloud, using the optional argument \verb=offset=. See Section \ref{sec:lineproflte} for details.


\subsection{Escape Probability Geometries}
\label{sec:escapeprobgeom}

\despotic\ currently supports three possible geometries that can be used when computing escape probabilities, and which are controlled by the \verb=escapeProbGeom= optional argument to most \despotic\ functions. This optional argument, if included, must be set equal to one of the three strings \verb='sphere'= (the default), \verb='slab'=, or \verb='LVG'=. In the examples provided in the previous sections, the methods \verb=cloud.lineLum=, \verb=cloud.dEdt=, \verb=cloud.setTempEq=, \verb=cloud.setGasTempEq=, \verb=cloud.setDustTempEq=, and \verb=cloud.tempEvol= all accept the optional argument 
\verb=escapeProbGeom=.




\clearpage

\section{\despotic\ Cloud Files}
\label{sec:cloudfiles}

\subsection{Overall Structure}

\despotic\ cloud files contain descriptions of clouds that can be read by the cloud class, using either the class constructor or the read method; see Section~\ref{sec:cloud} for details. This section contains a description of the format for these files. It is recommended but not required that cloud files have names that end in the extension \verb=.desp=.

Each line of a cloud file must be blank, contain a comment starting with the character \verb=#=, or contain a key-value pair formatted as
\begin{verbatim}
key = value
\end{verbatim}
The line may also contain comments after \verb=value=, again beginning with \verb=#=. Any content after \verb=#= is treated as a comment and is ignored. \despotic\ keys are case-insensitive, and whitespace around keys and values are ignored. The full set of allowed keys and their functions is listed in Table \ref{tab:cloudfiles}. All quantities must be in CGS units. Key-value pairs may be placed in any order, with the exception of the key \verb=H2opr=, which provides a means of specify the ratio of ortho-to-para-H$_2$, instead of directly setting the ortho- and para-H$_2$ abundances. If this key is specified, it must precede the key \verb=xH2=, which gives the total H$_2$ abundance including both ortho- and para- species\footnote{In v1.0.4, \texttt{H2OPR} and \texttt{XH2} are implemented as python properties, and will automatically update \texttt{comp.xpH2} and \texttt{comp.xoH2} when changed interactively}. Not all keys are required to be present. If left unspecified, most quantities default to a fiducial Milky Way value (if a reasonable one exists, e.g.~for the gas-dust coupling constant and ISRF strength) or to 0 (if it does not, e.g.~for densities and chemical abundances).


\begin{table}
\begin{center}
\begin{tabular}{lll}
\hline\hline
Key & Units & Description
\\ \hline\hline
\\
\multicolumn{3}{l}{Physical properties} \\
\hline
\verb=nH= & cm$^{-3}$ & Volume density of H nuclei \\
\verb=colDen= & cm$^{-3}$ & Column density of H nuclei, averaged over cloud area \\
\verb=sigmaNT= & cm s$^{-1}$ & Non-thermal velocity dispersion \\
\verb=Tg= & K & Gas temperature \\
\verb=Td= & K & Dust temperature \\
\\
\multicolumn{3}{l}{Dust properties} \\ \hline
\verb=alphaGD= & erg cm$^3$ K$^{-3/2}$ & Gas-dust coupling coefficient \\
\verb=sigmaD10= & cm$^2$ H$^{-1}$ & Dust cross section per H to thermal radiation at 10 K \\
\verb=sigmaDPE= & cm$^2$ H$^{-1}$ & Dust cross section per H to $8-13.6$ eV photons \\
\verb=sigmaDISRF= & cm$^2$ H$^{-1}$ & Dust cross section per H averaged over the ISRF \\
\verb=betaDust= & - & Dust spectral index in the infrared \\
\verb=Zdust= & - & Dust abundance relative to Milky Way\\
\\
\multicolumn{3}{l}{Radiation field} \\ \hline
\verb=TCMB= & K & Temperature of the cosmic microwave background \\
\verb=TradDust= & K & Temperature of the dust-trapped IR radiation field \\
\verb=ionRate= & s$^{-1}$ H$^{-1}$ & Primary ionization rate due to cosmic rays and x-rays\\
\verb=chi= & - & ISRF strength, normalized to Solar neighborhood value\\
\\
\multicolumn{3}{l}{Chemical composition} \\ \hline 
\verb=emitter= & - & See Section \ref{sec:cloudfiles_emitters}
\\ \hline
\end{tabular}
\caption{
\label{tab:cloudfiles}
List of allowed cloud file keys and their meanings.
}
\end{center}
\end{table}

\subsection{Emitters}
\label{sec:cloudfiles_emitters}

The \verb=emitter= key is more complex than most, and requires special mention. Lines describing emitters follow the format
\begin{verbatim}
emitter = name abundance [extrapolate] [energySkip] [file:FILE] [url:URL]
\end{verbatim}
Here the brackets indicate optional items, and the optional items may appear in any order, but must be after the two mandatory ones.

The first mandatory item, \verb=name=, gives name of the emitting molecule or atom. Note that molecule and atom names are case sensitive, in the sense that \despotic\ will not assume that ``co" and ``CO" describe the same species. Any string is acceptable for \verb=name=, but if the file or URL containing the data for that species is not explicitly specified, the name is used to guess the corresponding file name in the Leiden Atomic and Molecular Database (LAMDA) -- see Section \ref{sec:lamda}. It is therefore generally advisable to name a species following LAMDA convention, which is that molecules are specified by their chemical formula, with a number specifying the atomic weight preceding the if the species is not the most common isotope. Thus LAMDA refers to $^{28}$Si$^{16}$O (the molecule composed of the most common isotopes) as sio, $^{29}$Si$^{16}$O as 29sio, and $^{12}$C$^{18}$O as c18o. The automatic search for files in LAMDA also includes common variants of the file name used in LAMDA. The actual file name from which \despotic\ reads data for a given emitter is stored in the emitterData class -- see Section \ref{sec:emitterData}.

The second mandatory item, \verb=abundance=, gives the abundance of that species relative to H nuclei. For example, an abundance of 0.1 would indicate that there is 1 of that species per 10 H nuclei.

The optional items \verb=extrapolate= and \verb=energySkip= change how \despotic\ performs computations with that species. If \verb=extrapolate= is omitted, \despotic\ will raise an error if any attempt is made to calculate a collision rate coefficient between that species and one of the bulk components (H, He, etc.) that is outside the range tabulated in the data file. If \verb=extrapolate= is specified, \despotic\ will instead extrapolate off the table by assuming that the downward collision rate coefficient varies as a powerlaw in temperature, with the powerlaw slope and normalization determined by the two closest table elements. The optional item \verb=energySkip= specifies that a species should be ignored when computing heating and cooling rates via the \verb=cloud.dEdt= method. However, line emission from that species can still be computed using the \verb=cloud.lineLum= method. This option is therefore useful for including species for which the line emission is an interesting observable, but which are irrelevant to the thermal balance and thus can be omitted when calculating cloud thermal properties in order to save computational time.

Finally, the optional items \verb=file:FILE= and \verb=url:URL= specify locations of atomic and molecular data files, either on the local file system or on the web. This capability is useful in part because some LAMDA files do not follow the usual naming convention, or because for some species LAMDA provides more than one version of the data for that species (e.g.~two versions of the data file for atomic C exist, one with only the low-lying IR levels, and another including the higher-energy UV levels). File specifications must be of the form \verb=file:FILE= with \verb=FILE= replaced by a file name, which can include both absolute and relative paths. If no path or a relative path is given, \despotic\ searches for the file first in the current directory, and then in the directory \verb=$DESPOTIC_HOME/LAMDA=, where \verb=$DESPOTIC_HOME= is an environment variable. If it is not specified, \despotic\ just looks for a directory called LAMDA relative to the current directory.

The \verb=url:URL= option can be used to specify the location of a file on the web, usually somewhere on the LAMDA website. It must be specified as \verb=url:URL=, where \verb=URL= is replaced by an absolute or relative URL. If an absolute URL is given, \despotic\ attempts to download the file from that location. If a relative URL is given, \despotic\ attempts to download the file from at \verb=http://$DESPOTIC_LAMDAURL/datafiles/URL=, where \verb=$DESPOTIC_LAMDAURL= is an environment variable. If this environment variable is not specified, \despotic\ searches for the file at \verb=http://home.strw.leidenuniv.nl/~moldata/URL=.

\clearpage

\section{Chemistry and Chemical Networks}
\label{sec:chem}

The chemistry capabilities in \despotic, which are new as of version 1.1.0, are located in the \verb=despotic.chemistry= sub-package. This package defines a generic class to describe chemical reaction networks, and two procedures that can operate on chemical networks and their associated clouds to compute chemical equilibria and time-dependent chemical evolution. These capabilities are add-ons to the capabilities of earlier versions of \despotic, and versions 1.1.0 retains full backwards compatibility with earlier versions.

\subsection{Operations on Chemical Networks: Time Evolution and Equilibria}

In its most generic form, a chemical network is defined by a list of $N$ chemical species, a set of abundances $\mathbf{x}$ for those species (defined relative to H nuclei, like all other abundances in \despotic), and a function $f(\mathbf{x},\mathbf{p})$ that gives the time rate of change of those abundances $d\mathbf{x}/dt = f(\mathbf{x},\mathbf{p})$. The function $f$ generally depends on the instantaneous abundances $\mathbf{x}$, and may also depend on any number of other parameters $\mathbf{p}$. Examples of quantities that might enter $\mathbf{p}$ include but are not limited to the ambient radiation field (for photochemical reactions), the cosmic ray ionization rate, abundances of species that are not explicitly included in the network, and the gas density and temperature. Given these definitions, \despotic\ is capable of two operations:
\begin{itemize}
\item Given an initial set of abundances at $\mathbf{x}(t_0)$ at time $t_0$, compute the abundances at some later time $t_1$. This is simply a matter of numerically integrating the ordinary differential equation $d\mathbf{x}/dt = f(\mathbf{x},\mathbf{p})$ from $t_0$ to $t_1$, where $f$ is a known function that is defined by the chemical network. In \despotic, this capability is implemented by the routine \verb=chemEvol= in the \verb=despotic.chemistry.chemEvol= module. The \verb=cloud= class contains a wrapper around this routine, which allows it to be called to operate on a specific instance of \verb=cloud=.
\item Find an equilibrium set of abundances $\mathbf{x}_{\rm eq}$ such that $d\mathbf{x}/dt = f(\mathbf{x}_{\rm eq},\mathbf{p}) = 0$. Note that these is in general no guarantee that such an equilibrium exists, or that it is unique, and there are no general techniques for identifying such equilibria for arbitrary vector functions $f$. \despotic\ handles this problem by explicitly integrating the ODE $d\mathbf{x}/dt = f(\mathbf{x},\mathbf{p})$ until $\mathbf{x}$ reaches constant values (within some tolerance) or until a specified maximum time is reached. In \despotic, this capability is implemented by the routine \verb=setChemEq= in the \verb=despotic.chemistry.setChemEq= module. The \verb=cloud= class contains a wrapper around this routine, which allows it to be called to operate on a specific instance of \verb=cloud=.
\end{itemize}
Full details of these modules are given in Sections \ref{sec:chemevol} and \ref{sec:setchemeq}.

\subsection{The NL99 Network}

As of version 1.1.0, \despotic\ only ships with a a single-predefined chemistry network: the reduced C-O network introduced by Nelson \& Langer (1999, \textit{Astrophysical Journal}, 524, 923; hereafter NL99). Readers are refereed to that paper for a full description of the network and the physical approximations on which it relies. To summarize briefly here, the network is intended to capture the chemistry of carbon and oxygen as it occurs at moderate densities and low temperatures in H$_2$-dominated clouds. It includes the species C~\textsc{i}, C$^+$, CH$_x$, CO, HCO$^+$, H$_3^+$, He$^+$, O~\textsc{i}, OH$_x$, M, and M$^+$. Several of these are ``super-species" that agglomerate several distinct species with similar reaction rates and pathways, including CH$_x$ (where $x=1-4$), OH$_x$ (where $x=1-2$), and M and M$^+$ (which are stand-ins for metals such as iron and nickel). The network involves two-body reactions among these species, as well as photochemical reactions induces by UV from the ISRF and reactions initiated by cosmic ray ionizations. In addition to the initial abundances of the various species, the network depends on the ISRF, the ionization rate, and the total abundances of C and O nuclei.

In implementing the NL99 network in \despotic\ there are a three design choices to be made. First, photochemical and ionization reactions depend on the UV radiation field strength and the ionization rate. When performing computations on a cloud, \despotic\ takes these from the parameters \verb=chi= and \verb=ionRate= that are part of the \verb=radiation= class attached to the cloud.

Second, photochemical reactions depend on the amount of shielding against the ISRF provided by dust, and, in the case of the reaction $\mbox{CO} + h\nu \rightarrow \mbox{C} + \mbox{O}$, line shielding by CO and H$_2$. Following its usual approximation for implementing such shielding in a one-zone model, \despotic\ takes the relevant column density to be $N_{\rm H}/2$, where $N_{\rm H}$ is the column density \verb=colDen= of the cloud, so that the typical amount of shielding is assumed to correspond to half the area-averaged column density. For the dust shielding, NL99 express the shielding in terms of the V-band extinction $A_V$; unless instructed otherwise, \despotic\ computes this via
\begin{displaymath}
A_V = 0.4 \sigma_{\rm PE} (N_{\rm H}/2).
\end{displaymath}
This ratio of V-band to 1000 \AA\ extinction is intermediate between the values expected for Milky Way and SMC dust opacity curves, as discussed in Krumholz, Leroy, \& McKee (2011, \textit{Astrophysical Journal}, 731, 25). However, the user may override this choice. For line shielding, \despotic\ computes the H$_2$ and CO column densities via
\begin{eqnarray*}
N_{\rm H_2} & = & x_{\rm H_2} N_{\rm H}/2 \\
N_{\rm CO} & = & x_{\rm CO} N_{\rm H}/2,
\end{eqnarray*}
which amounts to assuming that the CO and H$_2$ are uniformly distributed. Note that the NL99 network explicitly assumes $x_{\rm H_2} = 0.5$, as no reactions involving atomic H are included. These column densities are then used to find a shielding factor by interpolating the tabulated values of van Dishoeck \& Black (1998, \textit{Astrophysical Journal}, 334, 771).

The third choice is how to map between the species included in the chemistry network and the actual emitting species that are required to compute line emission, cooling, etc. This is non-trivial both because the chemical network includes super-species, because the chemical network does not distinguish between ortho- and para- sub-species while the rest of \despotic\ does, and because the network does not distinguish between different isotopomers of the same species, while the rest of \despotic\ does. This does not create problems in mapping from cloud emitter abundances to the chemical network, since the abundances can simply be summed, but it does create a question about how to map output chemical abundances computed by the network into the abundances of emitters that can be operated on by the remainder of \despotic. In order to handle this issue, \despotic\ makes the following assumptions: (1) OH$_x$ is divided evenly between OH and OH$_2$; (2) the abundances of the para- and ortho- states of a given species are equal; (3) the abundances ratios of all isotopomers of a species remain fixed as reactions occur, so, for example, the final abundance ratio of C$^{18}$O to C$^{16}$O as computed by the chemical network is always the same as the initial one.


\subsection{Implementing New Chemical Networks via the \texttt{chemNetwork} Class}

\despotic\ implements chemical networks through the abstract base class \verb=chemNetwork=, which is defined by module \verb=despotic.chemistry.chemNetwork=. This class defines the required elements that all chemistry networks must contain; users who wish to implement their own chemistry networks must derive them from this class, and must override the class methods listed below. Users are encouraged to examine the \verb=NL99= class for an example of how to derive a new chemical network class from \verb=chemNetwork=.

The required non-callable attributes of a chemistry network class \verb=cn= are as follows:
\begin{itemize}
\item \verb=cn.specList= is a list of strings the describes the chemical species included in the network. The names in \verb=specList= can be arbitrary, and are not used for any purpose other than providing human-readable labels on outputs.
\item \verb=cn.x= is a numpy array of rank 1, with each element specifying the abundance of a particular species in the network. The number of elements in the array must match the length of \verb=cn.specList=. As with all abundances in \verb=despotic=, abundances must be specified relative to H nuclei, so that if, for example, \verb=x[3]= is $0.1$, this means that there is 1 particle of species 3 per 10 H nuclei.
\item \verb=cn.cloud= is an instance of the \verb=cloud= class to which the chemical network is attached. This can be \verb=None=, as chemical networks can be free-standing at not attached to specified instances of \verb=cloud=. However, much of the functionality of chemical networks is based around integration with the \verb=cloud= class.
\end{itemize}
The required callable attributes are
\begin{itemize}
\item \verb+cn.__init__(self, cloud=None, info=None)+ is the initialization method. It must accept two keyword arguments. The first, \verb=cloud=, is an instanced of the \verb=cloud= class to which this chemical network will be attached. This routine should set \verb+cn.cloud+ equal to the input \verb=cloud= instance, and it may also extract information from the input \verb=cloud= instances in order to initialize \verb=cn.x= or any other required quantities. The second keyword argument, \verb=info=, is a dict containing any additional initialization parameters that the chemical network can be or must be passed upon instantiation.
\item \verb+cn.dxdt(self, xin, time)+ is a method that computes the time derivative of the abundances. Given an input numpy array of abundances \verb=xin= (which is the same shape as \verb=cn.x=) and a time \verb=time=, it must return a numpy array giving the time derivative of all abundances in units of s$^{-1}$.
\item \verb+cn.applyAbundances(self, addEmitters=False)+ is a method to take the abundances stored in the chemical network and use them to update the abundances of the corresponding emitters in the \verb=cloud= instances associated with this chemical network. This method is called at the end of every chemical calculation, and is responsible for copying information from the chemical network back into the cloud. The optional Boolean argument \verb=addEmitters=, if \verb=True=, specifies that the method should attempt to not only alter the abundances of any emitters associated with the cloud, it should also attempt to add new emitters that are included in the chemical network, and whose abundances are to be determined from it. It is up to the user whether or not to honor this request and implement this behavior.
\end{itemize}

Once a chemical network class that defines the above methods has been defined, that class can be passed as an argument associated with the \verb=network= keyword to the \verb=cloud.setChemEq= and \verb=cloud.chemEvol= methods, and these methods will automatically perform chemical calculations using the input network.

Finally, \verb=chemNetwork= defines a property \verb=abundances=, which returns the abundance information defined in \verb=cn.x= as a object of class \verb=abundanceDict=. This class is a utility class that provides an interface to the chemical abundances in a network that operates like a Python dict. For example, to print the abundance of CO in a chemical network, and then set the abundance of C$^+$ to zero, one can simply type
\begin{verbatim}
print cn.abundances['CO']
cn.abundances['C+'] = 0.0
\end{verbatim}
This save the user the trouble of remembering the numerical indices for CO and C$^+$ in a given network, and provides a means for external programs to access the abundances of particular species in a manner that is independent of the mapping between species name and index number, which might vary between two chemical networks that both contain the same species. Full details of the \verb=abundanceDict= class are given in Section \ref{sec:abundancedict}.

\clearpage

\section{Atomic and Molecular Data}
\label{sec:lamda}

This section describes how \despotic\ handles atomic and molecular data, both in terms of its local cache of LAMDA files and its internal representation of them.

\subsection{The Local Database}

\despotic\ uses atomic and molecular data in the format specified by the Leiden Atomic and Molecular Database, described at \url{http://home.strw.leidenuniv.nl/~moldata/}. When \despotic\ downloads a file from LAMDA, either by automatically guessing the name or if a URL is manually specified (see Section \ref{sec:cloudfiles_emitters}), it stores a local copy for future use. The next time the same emitter is used, unless \despotic\ is given an explicit URL from which the file should be fetched, it will use the local copy instead of re-downloading the file from LAMDA. (However, see Section \ref{sec:database_updates}.)

The location of the database is up to the user, and is specified through the environment variable \verb=$DESPOTIC_HOME=. If this environment variable is set, LAMDA files will be places in the directory \verb=$DESPOTIC_HOME/LAMDA=, and that is the default location that will be searched when a file is needed. If the environment variable \verb=$DESPOTIC_HOME= is not set, \despotic\ looks for files in a subdirectory LAMDA of the current working directory, and caches files in that directory if they are downloaded. It is recommended that users set a \verb=$DESPOTIC_HOME= environment variable when working with \despotic, so as to avoid downloading and caching multiple copies of LAMDA for different projects in different directories.


\subsection{Keeping the Database Up to Date}
\label{sec:database_updates}

The data in LAMDA is updated regularly as new calculations or laboratory experiments are published. Some of these updates add new species, but some also provide improved data on species that are already in the database.  \despotic\ attempts to ensure that its locally cached data are up to date by putting an expiration date on them. By default, if \despotic\ discovers that a given data file is more than six months old, it will re-download that file from LAMDA. This behavior can be overridden by manually specifying a file name, either in the cloud file (Section \ref{sec:cloudfiles_emitters}) or when invoking the \verb=cloud.addEmitter= or \verb=emitter.__init__= methods. Users can also force updates of the local database more frequently using the \verb=refreshLamda= function -- see Section \ref{sec:refreshLamda}.


\subsection{How \despotic\ Deals with Atomic and Molecular Data Internally}

When it is running, \despotic\ maintains a list of emitting species for which data have been read within the \verb=emitter= module (Section \ref{sec:emitter}). Whenever a new emitter is created, either for an existing cloud, for a new cloud being created, or as a free-standing object of the emitter class, \despotic\ checks the emitter name against the central list. If the name is found in the list, \despotic\ will simply use the stored data for that object rather than re-reading the file containing the data. This is done as an efficiency measure, and also to ensure consistency between emitters of the same species associated with different clouds. However, this model has some important consequences of which the user should be aware. First, since data on level structure, collision rates, etc.\ (everything stored in the \verb=emitterData= class -- Section \ref{sec:emitterData}) is shared between all emitters of the same name, and any alterations made to the data for one emitter will affect all others of the same name. Second, it is not possible to have two emitters of the same name but with different data. Should a user desire to achieve this for some reason (e.g.~to compare results computed using an older LAMDA file and a newer one), the way to achieve this is to give the two emitters different names, such as 'co\_ver1' and 'co\_ver2'. Finally, maintenance of a central emitter list affects how deepcopy and pickling operations operate on emitters. See Section \ref{sec:emitter} for details.

\clearpage

\section{Full Description of Despotic Modules}
\label{sec:full}

Below is a full listing of all the modules included in \despotic. Except where noted otherwise, modules define a single class of the same name, and all the functions provided by that module are associated with that class. Note that all \despotic\ classes and functions include a docstring, so their call signatures and return values can be read using the standard Python help utility.

\subsection{cloud}
\label{sec:cloud}

The \verb=cloud= module defines the class \verb=cloud=. The non-callable attributes of this class are listed in Table \ref{tab:cloudattr}. The callable attributes are discussed in the following sections.

\begin{table}
\begin{center}
\begin{tabular}{lll}
\hline\hline
Name & Type & Meaning \\
\hline\hline
\texttt{nH} & float & Number density of H nuclei \\
\texttt{colDen} & float & Column density of H nuclei \\
\texttt{sigmaNT} & float & Non-thermal velocity dispersion \\
\texttt{dVdr} & float & Radial velocity gradient \\
\texttt{Tg} & float & Gas temperature \\
\texttt{Td} & float & Dust temperature \\
\texttt{comp} & class composition & Bulk composition \\
\texttt{dust} & class dustprop & Dust properties \\
\texttt{rad} & class radiation & Radiation field properties \\
\texttt{emitters} & dict & emitters in the cloud; keys are emitter name,\\
& & \qquad values are of class emitter \\
\hline
\end{tabular}
\caption{
\label{tab:cloudattr}
Non-callable attributes of the \texttt{cloud} class.
}
\end{center}
\end{table}

\subsubsection{\texttt{cloud.\_\_init\_\_}}

Call signature:

\begin{verbatim}
cloud.__init__(self, fileName=None, verbose=False)
\end{verbatim}

This initializes a \texttt{cloud} object. The optional argument \texttt{fileName} is a string that specifies the name of a \texttt{despotic} cloud file in the format specified in Section \ref{sec:cloudfiles}. The optional argument \texttt{verbose} is a Boolean that, if True, specifies that verbose output should be printed as a file is read. This procedure returns nothing.

\subsubsection{\texttt{cloud.read}}

Call signature:

\begin{verbatim}
cloud.read(self, fileName, verbose=False)
\end{verbatim}

This reads a \texttt{despotic} cloud file in the format specified in Section \ref{sec:cloudfiles} and uses its contents to set the properties of the calling \texttt{cloud} object. The argument \verb=fileName= is a string that gives the name of the file to be read. The optional argument \texttt{verbose} is a Boolean that, if True, specifies that verbose output should be printed as a file is read. This procedure returns nothing.

\subsubsection{\texttt{cloud.addEmitter}}
\label{sec:cloud.addEmitter}

Call signature:

\begin{verbatim}
cloud.addEmitter(self, emitName, emitAbundance, emitterFile=None, \
                       emitterURL=None, energySkip=False, \
                       extrap=False):
\end{verbatim}

This routine adds an emitter to the \texttt{emitters} dict. The argument \verb=emitName= is a string that becomes the key corresponding to this emitter in the \verb=emitter= dict. The argument \verb=emitAbundance= gives the abundance of the emitting species relative to H nuclei. The optional arguments \verb=emitterFile= and \verb=emitterURL= are strings specifying the name of a file or URL from which the LAMDA-formatted file containing data on the emitting species is to be read. These are treated exactly as specifications of file and URL in a \despotic\ cloud file; see Section \ref{sec:cloudfiles_emitters}. Similarly, optional arguments \verb=energySkip= and \verb=extrap= are Booleans that are equivalent to the keys \verb=extrapolation= and \verb=energySkip= in a \despotic\ cloud file. This procedure returns nothing.


\subsubsection{\texttt{cloud.setVirial}}

Call signature:

\begin{verbatim}
cloud.setVirial(self, alphaVir=1.0, setColDen=False, setnH=False)
\end{verbatim}

This routine sets the non-thermal velocity dispersion, column density, or volume density to the value required to produce a specified virial ratio. By default, \verb=colDen= and \verb=nH= are left unchanged, and \verb=sigmaNT= for the cloud is altered. The optional argument \verb=alphaVir= is a float specifies the value of the virial ratio used in the computation, with a default value of 1.0. The optional arguments \verb=setColDen= and \verb=setnH= are Booleans that specify, respectively, that \verb=sigmaNT= and \verb=nH= should be fixed and \verb=colDen= altered, or \verb=sigmaNT= and \verb=colDen= fixed and \verb=nH= altered, so as to produce the desired virial ratio. This procedure returns nothing.


\subsubsection{\texttt{cloud.lineLum}}
\label{sec:linelum}

Call signature:

\begin{verbatim}
lum = cloud.lineLum(self, emitName, LTE=False, noClump=False, \
                    transition=None, thin=False, intOnly=False, \
                    TBOnly=False, lumOnly=False, \
                    escapeProbGeom='sphere', \
                    noRecompute=False)
\end{verbatim}

This routine returns the luminosities of all the lines for a specified emitter. The argument \verb=emitName= is a string giving the name of the emitter whose lines are to be calculated. The optional arguments \verb=LTE=, \verb=thin=, and \verb=noClump= are Booleans that, if True, specify that the level populations are to be set to their LTE values, that they are to be computed assuming that the cloud is optically thin, and that they are to be computed using a clumping factor of unity, respectively. The optional argument \verb=noRecompute= is a Boolean that, if True, causes the level populations not to be recalculated at all; instead, stored values are used to compute the luminosities. The optional argument \verb=escapeProbGeom= is a string specifying which geometry to assume when calculating escape probabilities (see Section \ref{sec:escapeprobgeom}). The optional argument \verb=transition= is a sequence of two arrays, the first of which specifies a list of upper states and the second of which specifies a list of lower states. The routine will then compute only the lines corresponding to transitions between those two states. The default behavior is to perform the calculation for all transitions with non-zero Einstein $A$ coefficients.

The return value \verb=lum= is by default returns a sequence of dicts, but this behavior can be altered by the optional keywords \verb=intOnly=, \verb=TBOnly=, and \verb=lumOnly=; these are all Booleans. If none of them are True, the routine returns a sequence of dicts, each corresponding to one line. Each dict contains the following entries: \verb=freq= is the line frequency in Hz, \verb=upper= is the index of the upper level, \verb=lower= is the index of the lower level, \verb=TUpper= is the energy of the upper state in K, \verb=Tex= is the excitation temperature describing the relative populations of the upper and lower levels for this line, \verb=tau= is the gas optical depth in the line, \verb=tauDust= is the dust optical depth in the line, \verb=lumPerH= is the total rate of energy emission per H nucleus in the line, in units of erg s$^{-1}$ H$^{-1}$, \verb=intIntensity= is the frequency-integrated intensity of the line with the CMB subtracted off, in erg cm$^{-2}$ s$^{-1}$ sr$^{-1}$, and \verb=intTB= is the velocity-integrated brightness temperature of the line, in K km s$^{-1}$. If \verb=intOnly=, \verb=TBOnly=, or \verb=lumOnly= are True, instead of returning a dict, the routine returns only an array corresponding to the entries \verb=intIntensity=, \verb=intTB=, or \verb=lumPerH= in the default dict.


\subsubsection{\texttt{cloud.dEdt}}
\label{sec:dEdt}

Call signature:

\begin{verbatim}
rates = cloud.dEdt(self, c1Grav=0.0, thin=False, LTE=False, \
                 fixedLevPop=False, noClump=False, \
                 escapeProbGeom='sphere', PsiUser=None, \
                 sumOnly=False, dustOnly=False, gasOnly=False, \
                 dustCoolOnly=False, dampFactor=0.5, \
                 verbose=False, overrideSkip=False)
\end{verbatim}

This procedure returns the rates of heating and cooling for the cloud. When called, by default this routine computes the level populations of all emitting species not marked with \verb=energySkip= using the \verb=emitters.setLevPopEscapeProb= method (see Section \ref{sec:setlevpopescapeprob}).

By default the return value \verb=rates= is a dict containing the following keys and values: \verb=GammaPE= is the gas photoelectric heating rate; \verb=GammaCR= is that cosmic ray / x-ray ionization heating rate; \verb=GammaGrav= is the gas heating rate from adiabatic gravitational compression; \verb=GammaDustISRF= is the dust heating rate from the interstellar radiation field; \verb=GammaDustCMB= is the dust heating rate from the CMB; \verb=GammaDustIR= is the dust heating rate from the background IR radiation field; \verb=GammaDLine= is the dust heating rate due to absorption of line radiation; \verb=PsiGD= is the gas-dust energy exchange rate, with a positive value indicating net transfer of energy from dust to gas; \verb=LambdaDust= is the dust cooling rate due to thermal emission; finally, \verb=LambdaLine= is a dict containing the cooling rate due to all emitting species, with the name of the species as the dict key and the cooling rate as its value. All quantities are given in units of erg s$^{-1}$ H$^{-1}$.

The optional arguments have the following functions: \verb=c1Grav= is a float specifying the constant $C_1$ used to compute the gravitational heating rate, with a default value of 0 indicating no gravitational heating; \verb=LTE= is a Boolean that, if True, causes the level populations to be set to their LTE values; \verb=thin= is a Boolean that, if True, causes the level populations to be computed assuming that the cloud is optically thin; \verb=fixedLevPop= is a Boolean that, if True, causes the line heating and cooling rates to be computed using the currently-stored level populations for all emitters, rather than recomputing those level populations; \verb=noClump= is a Boolean that, if True, causes the clumping factor to be set to 1.0 for purposes of computing the level populations; \verb=escapeProbGeom= is a string specifying which geometry to assume when calculating escape probabilities (see Section \ref{sec:escapeprobgeom}); \verb=PsiUser= is a callable giving a user-specified heating rate for the gas and dust (see below for details); \verb=sumOnly= is a Boolean that, if True, specifies that only the sum of the heating and cooling terms should be returned, not the individual ones; \verb=dustOnly= is a Boolean that, if True, specifies that only the dust heating and cooling terms should be computed; \verb=gasOnly= is a Boolean that, if True, specifies that only the gas heating and cooling terms should be computed; \verb=dampFactor= is a float that gives the damping factor used in the level population calculations; \verb=overrideSkip= specifies that line heating and cooling rates should be computed even from species marked by \verb=energySkip=; finally, \verb=verbose= causes status messages to be printed as the computation proceeds.

A number of optional arguments can alter the contents of the dict that is returned. If \verb=PsiUser= is not \verb=None=, this will cause the keys \verb=PsiUserGas= and \verb=PsiUserDust= to be added, giving the heating / cooling rate produced by the user function. If \verb=sumOnly= is True, then the returned dict contains only four entries, \verb=dEdtGas=, \verb=maxAbsdEdtGas=, \verb=dEdtDust=, and \verb=maxAbsdEdtDust=. These give, respectively, the net rate of heating / cooling for gas, the largest of the absolute values of any of the heating and cooling terms for gas, and the corresponding two properties for dust. If \verb=gasOnly= is True, then \verb=GammaISRF=, \verb=GammaDLine=, \verb=LambdaDust= and \verb=PsiUserDust= are omitted from the dict. If \verb=dustOnly= is True, then \verb=GammaPE=, \verb=GammaCR=, \verb=LambdaLine=, and \verb=GammaDLine= are omitted from the dict. If \verb=dustCoolOnly= is True, then \verb=GammaDustISRF=, \verb=GammaDustCMB=, and \verb=GammaDustIR= are omitted as well. If both \verb=gasOnly= and \verb=sumOnly= are set, then the dict contains only \verb=dEdtGas= and \verb=maxAbsdEdtGas=, and similarly if both \verb=dustOnly= or \verb=dustCoolOnly= and \verb=sumOnly= are set. Note that, if \verb=dustOnly= or \verb=dustCoolOnly= are set together with \verb=sumOnly=, the summed heating and cooling rate for dust includes only those terms that would have been included in the dict has \verb=sumOnly= not been set.

The optional argument \verb=PsiUser= can be used to specify an additional heating and cooling function. This argument must be set equal to a callable, which takes one object of class \verb=cloud= as an argument, and returns a two-element array. The first element is the gas heating / cooling rate (with positive indicating heating), and the second is the dust heating / cooling rate, both in erg s$^{-1}$ H$^{-1}$. If this argument is not \verb=None= when \verb=dEdt= is called, then \verb=dEdt= will call the specified callable, passing it the calling cloud object as its argument.

\subsubsection{\texttt{cloud.setTempEq}}
\label{sec:settempeq}

Call signature:

\begin{verbatim}
success = cloud.setTempEq(self, c1Grav=0.0, thin=False, noClump=False, \
                      LTE=False, Tinit=None, fixedLevPop=False, \
                      escapeProbGeom='sphere', PsiUser=None, \
                      verbose=False, tol=1e-4)
\end{verbatim}

This procedure sets the cloud gas and dust temperature \verb=Tg= and \verb=Td= to their equilibrium values, such that the net rates of heating and cooling for both gas and dust are 0 to within a specified tolerance (see below). The optional arguments \verb=c1Grav=, \verb=LTE=, \verb=thin=, \verb=fixedLevPop=, \verb=escapeProbGeom=, \verb=PsiUser=, and \verb=verbose= behave the same as for the routine \verb=dEdt= (see Section \ref{sec:dEdt}). The optional argument \verb=Tinit= is a sequence of two floats, which specifies initial guesses for the gas and dust temperatures to be used in the iterative solver. If it is left equal to \verb=None=, then the currently-stored gas and dust temperatures are used, or 10 K if the currently-stored values are 0.

The \verb=tol= argument specifies the tolerance within which the heating and cooling rates are to be set to zero. The residual for this solve is defined as the larger of \verb=dEdtGas= / \verb=maxAbsdEdtGas= and \verb=dEdtDust= / \verb=maxAbsdEdtDust=, where these are the values returned by the \verb=cloud.dEdt= function (see Section \ref{sec:dEdt}); they represent the net heating / cooling rate of gas normalized to the largest of the absolute values of any of the individual terms contributing to heating and cooling, and vice versa. \textit{Note that the numerators of these terms are evaluated at the current temperatures, but the denominator is evaluated at the initially-guessed temperatures.} The tolerance is defined in this way in order to guarantee that the residual is monotonically decreasing as one approaches the correct solution, which need not be the case if both the numerator and denominator are evaluated at the current temperature. The temperature calculation is considered converged when this residual falls below \verb=tol=.

This procedure returns True if the iteration converges, and False if it fails to converge.

\subsubsection{\texttt{cloud.setDustTempEq}}

Call signature:

\begin{verbatim}
success = cloud.setDustTempEq(self, PsiUser=None, Tdinit=None, \
                          noLines=False, noClump=False, \
                          verbose=False)
\end{verbatim}

This function is identical to \verb=cloud.setTempEq= (Section \ref{sec:settempeq}) except that the gas temperature \verb=Tg= is held fixed and only the dust temperature \verb=Td= is altered. The optional argument \verb=Tdinit= is a float giving an initial guess for the dust temperature. The optional argument \verb=noLines= specifies that the line heating of the dust should be ignored in this computation; this can be advantageous because in many situations line heating of the dust is negligible, and omitting line heating makes the calculation run much faster. All other optional arguments, and the return value, are the same as for \verb=cloud.setTempEq=.

This procedure returns nothing.

\subsubsection{\texttt{cloud.setGasTempEq}}

Call signature:

\begin{verbatim}
success = cloud.setGasTempEq(self, c1Grav=0.0, thin=False, noClump=False, \
                      LTE=False, Tginit=None, fixedLevPop=False, \
                      escapeProbGeom='sphere', PsiUser=None, verbose=False)
\end{verbatim}

This function is identical to \verb=cloud.setTempEq= (Section \ref{sec:settempeq}) except that the dust temperature \verb=Td= is held fixed and only the gas temperature \verb=Tg= is altered. The optional argument \verb=Tginit= is a float giving an initial guess for the dust temperature. All other optional arguments, and the return value, are the same as for \verb=cloud.setTempEq=.

\subsubsection{\texttt{cloud.tempEvol}}
\label{sec:tempevol}

Call signature:

\begin{verbatim}
out, time = cloud.tempEvol(self, tFin, tInit=0.0, c1Grav=0.0, noClump=False, \
                     thin=False, LTE=False, fixedLevPop=False, \
                     escapeProbGeom='sphere', nOut=100, dt=None, \
                     tOut=None, PsiUser=None, isobaric=False, \
                     fullOutput=False, verbose=False)
\end{verbatim}

This function calculates the evolution of the gas temperature of the cloud over a specified time period, assuming that the dust temperature and level populations reach equilibrium instantaneously. The argument \verb=tFin= is a float giving the time, in seconds, at which to end the integration. The optional argument \verb=tInit= specifies the time at which integration starts; the gas temperature \verb=cloud.Tg= initially stored in the cloud is taken to be at this initial time. The optional argument \verb=isobaric= is a Boolean that, if True, specifies that cooling is to be computed isobarically; the default is isochoric.

The optional arguments \verb=nOut=, \verb=dt=, and \verb=tOut= control the times at which data are output; \verb=nOut= is an integer that gives the number of equally-spaced time intervals between \verb=tFin= and \verb=tInit= at which to output. Alternately, \verb=dt= is float that gives the time interval (in seconds) between output times, or \verb=tOut= is a sequence specifying exact output times in seconds. If \verb=tOut= is specified, it must be sorted in increasing order. The optional arguments \verb=c1Grav=, \verb=noClump=, \verb=thin=, \verb=LTE=, \verb=fixedLevPop=, \verb=escapeProbGeom=, \verb=PsiUser=, and \verb=verbose= have the same meaning as for the routine \verb=cloud.dEdt= (see Section \ref{sec:dEdt}). 

This function returns two sequences. The second of these, \verb=time= is always a sequence of floats, and it contains the list of output times. The first sequence, \verb=out= is by default a sequence of floats containing the calculated gas temperatures in K at the times given in \verb=time=. If the optional argument \verb=fullOutput= is True, then \verb=out= is instead a sequence of cloud objects, each of which is a deep copy of the full state of the cloud at the specified output time.

\clearpage

\subsection{composition}
\label{sec:comp}

The \verb=composition= module defines the \verb=composition= class, which stores information and methods related to the bulk chemical composition of gas. The non-callable attributes of this class are listed in Table \ref{tab:comp}, and the callable attributes are described in the following sections.

\begin{table}
\begin{center}
\begin{tabular}{lll}
\hline\hline
Name & Type & Meaning \\
\hline\hline
\texttt{xHI} & float & H~\textsc{i} abundance per H nucleus \\
\texttt{xoH2} & float & ortho-H$_2$ abundance per H nucleus \\
\texttt{xpH2} & float & para-H$_2$ abundance per H nucleus \\
\texttt{xHe} & float & He abundance per H nucleus \\
\texttt{xe} & float & free electron abundance per H nucleus \\
\texttt{xHplus} & float & H$^+$ abundance per H nucleus \\
\texttt{mu} & float & mean mass per free particle, in units of $m_{\rm H}$ \\
\texttt{mhH} & float & mean mass per H nucleus, in units of $m_{\rm H}$ \\
\texttt{qIon} & float & energy added to the gas per primary ionization \\
\texttt{cv} & float & specific heat per H nucleus at constant volume \\
\hline
\end{tabular}
\caption{
\label{tab:comp}
Non-callable attributes of the \texttt{composition} class.
}
\end{center}
\end{table}

\subsubsection{\texttt{composition.computeDerived}}

Call signature:

\begin{verbatim}
composition.computeDerived(self, nH)
\end{verbatim}

This routine set the quantities \verb=composition.mu=, \verb=composition.muH=, and \verb=composition.qIon= based on the stored chemical composition, and the input volume density. This is specified by the argument \verb=nH=, which must be a float. This procedure returns nothing.


\subsubsection{\texttt{composition.computeCv}}

Call signature:

\begin{verbatim}
cv = computeCv(self, T, noSet=False, Jmax=40)
\end{verbatim}

This routine computes the specific heat per H nucleus $c_{v,\rm H}$ from the stored gas composition and the input temperature. The argument \verb=T= is a float or an array of floats that specifies the temperature. The optional argument \verb=noSet= is a Boolean. If it is False, the computed value of $c_{v,\rm H}$ is stored as \verb=composition.cv=; if it is True, the computed value is returned by not stored. The optional argument \verb=Jmax= specifies the maximum rotational quantum number to consider when computing the specific heat. Accurate results require that $T \ll J(J+1) \theta_{\rm rot}$, where $\theta_{\rm rot} = 85.3$ K is the rotational constant of H$_2$ in K. This procedure returns the computed value of $c_{v,\rm H}$. If \verb=T= is a float, the returned value is a float as well. If \verb=T= is an array, the returned value is an array of the same shape.


\clearpage

\subsection{dustProp}

The \verb=dustProb= module defines the \verb=dustProp= class, which stores properties of the dust. The non-callable attributes in the class are described in Table \ref{tab:dust}. This class has no callable attributes.

\begin{table}
\begin{center}
\begin{tabular}{lll}
\hline\hline
Name & Type & Meaning \\
\hline\hline
\texttt{sigma10} & float & Dust opacity per H nucleus to 10 K thermal radiation, in cm$^{-2}$ H$^{-1}$ \\
\texttt{sigmaPE} & float & Dust opacity per H nucleus to $8-13.6$ eV photons, in cm$^{-2}$ H$^{-1}$ \\
\texttt{sigmaISRF} & float & Dust opacity per H nucleus to ISRF photons that heat dust grains, \\
& & \quad in cm$^{-2}$ H$^{-1}$ \\
\texttt{Zd} & float & Dust abundance normalized to the Milky Way value \\
\texttt{beta} & float & Dust spectral index in the mm, $\sigma\propto \nu^\beta$ \\
\texttt{alphaGD} & float & Grain-gas collisional coupling coefficient, in cm$^3$ s$^{-1}$ K$^{-3/2}$ \\
\hline
\end{tabular}
\caption{
\label{tab:dust}
Non-callable attributes of the \texttt{dustProp} class.
}
\end{center}
\end{table}


\clearpage

\subsection{radiation}

The \verb=radiation= module defines the \verb=radiation= class, which describes the radiation field around a cloud. The non-callable attributes of the class are listed in Table \ref{tab:rad}, and the callable attributes are listed below.

\begin{table}
\begin{center}
\begin{tabular}{lll}
\hline\hline
Name & Type & Meaning \\
\hline\hline
\texttt{TCMB} & float & CMB temperature \\
\texttt{TradDust} & float & Temperature of the dust thermal radiation field \\
\texttt{ionRate} & float & Primary cosmic-ray / X-ray ionization rate, in s$^{-1}$ per H nucleus \\
\texttt{chi} & float & ISRF strength, normalized to the Solar neighborhood value \\
\hline
\end{tabular}
\caption{
\label{tab:rad}
Non-callable attributes of the \texttt{radiation} class.
}
\end{center}
\end{table}

\subsection{\texttt{radiation.\_\_init\_\_}}

Call signature:

\begin{verbatim}
radiation.__init__(self)
\end{verbatim}

This procedure creates a \verb=radiation= object with its parameters initialized to reasonable Milky Way defaults: CMB temperature of 2.73 K, dust radiation field temperature of 0, $\chi = 1$, and primary ionization rate $2\times 10^{-17}$ s$^{-1}$ H$^{-1}$.

\subsubsection{\texttt{radiation.ngamma}}

Call signature:

\begin{verbatim}
ngamma = radiation.ngamma(self, Tnu)
\end{verbatim}

This routine computes the photon occupation number of the CMB, $1/[\exp(-h\nu/k_B T_{\rm CMB}]$. The argument \verb=Tnu= is a float or array of floats, which specifies the value of $h\nu/k_B$ at which the computation is to be performed. The return value is a float or array of floats with the same shape as \verb=Tnu=.

\clearpage

\subsection{emitter}
\label{sec:emitter}

The \verb=emitter= module defines the class \verb=emitter=, and also stores a dict \verb=knownEmitterData=. This dict contains an entry for every \verb=emitter= class object for which a corresponding \verb=emitterData= object (see Section \ref{sec:emitterData}) has been created. The keys are the names of the \verb=emitterData= objects, and the values are the corresponding \verb=emitterData= objects. This list is maintained so that \despotic\ need not have a duplicate copy of the \verb=emitterData= for every instance of an emitter, and so that the LAMDA file need not be re-read every time an instance of a given emitting species is instantiated. Instead, different \verb=emitter= objects just contain shallow copies of a single master copy on the \verb=knownEmitterData= dict.

The \verb=emitter= class stores information about emitting species, and provides methods for performing computations on those species. It is distinct from the \verb=emitterData= class in that \verb=emitterData= stores only physical constants (e.g.~energies of quantum levels and Einstein coefficients for radiative transitions between them) that do not depend on the physical conditions in a given cloud. In contrast, the \verb=emitter= class stores information that does vary from cloud to cloud. The non-callable attributes of the class are described in Table \ref{tab:emitter}, and the callable attributes are described in the following sections.

\begin{table}
\begin{center}
\begin{tabular}{lll}
\hline\hline
Name & Type & Meaning \\
\hline\hline
\texttt{name} & string & Name of emitting species \\
\texttt{abundance} & float & Abundance relative to H nuclei\\
\texttt{data} & class \texttt{emitterData} & Physical data on this species \\
\texttt{levPop} & array(nlev) of float & Fractional populations of all levels \\
\texttt{levPopInitialized} & Boolean & Are level populations initialized? \\
\texttt{escapeProb} & array(nlev, nlev) of float & Escape probability for radiative \\
& & \quad transitions between each level\\
& & \quad pair \\
\texttt{escapeProbInitialized} & Boolean & Are escape probabilities \\
& & \quad initialized? \\
\texttt{energySkip} & Boolean & Should this emitter be skipped\\
& & \quad when computing heating / \\
& & \quad cooling rates? \\
\hline
\end{tabular}
\caption{
\label{tab:emitter}
Non-callable attributes of the \texttt{emitter} class.
}
\end{center}
\end{table}

\subsubsection{\texttt{emitter.\_\_init\_\_}}

Call signature:

\begin{verbatim}
emitter.__init__(self, emitName, emitAbundance, extrap=False, \
                 energySkip=False, emitterFile=None, emitterURL=None)
\end{verbatim}

This method initializes an object of type \verb=emitter=. The first argument \verb=emitName= is a string that gives the name of the emitting species, which will be stored as \verb=emitter.name=. The second argument, \verb=emitAbundance=, is a float that gives the abundance of the species relative to H nuclei; this will be stored as \verb=emitter.abundance=. The optional argument \verb=extrap= is a Boolean that specifies whether collision rates for this emitter can be extrapolated past the range provided in the LAMDA file. The optional argument \verb=energySkip= is a Boolean that specifies that, if True, specifies that this species is unimportant for heating or cooling, and thus can be skipped when computing heating and cooling rates. The optional arguments \verb=emitterFile= and \verb=emitterURL= are identical to the arguments of the same name in \verb=cloud.addEmitter= (see Section \ref{sec:cloud.addEmitter}).

This routine returns nothing.

The behavior of this routine with respect to the dict \verb=knownEmitterData= stored in the \verb=emitter= module is as follows. When \verb=emitter.__init__= is called, before attempting to read data from a LAMDA file, it first checks if the input \verb=emitName= matches any of the keys in \verb=knownEmitterData=. If a match is found, the \verb=data= attribute of this instance of \verb=emitter= is set equal to a shallow copy of the corresponding \verb=emitterData= in \verb=knownEmitterData=, and no files are read. If no match is found, on the other hand, this routine attempts to read the data for this species from a LAMDA file. If successful, the routine creates an \verb=emitterData= instances from that LAMDA file, stores it in \verb=knownEmitterData= with a key equal to the input \verb=emitName=, and then sets \verb=emitter.data= equal to a shallow copy of that \verb=emitterData=.

\subsubsection{\texttt{emitter.\_\_deepcopy\_\_}}

Call signature:

\begin{verbatim}
emitter.__deepcopy__(self, memo={})
\end{verbatim}

This method provides a custom deep copy operation for the \verb=emitter= class. A custom deep copy is required because of the way emitter data is handled. Since the \verb=data= attribute of this class should always be a shallow copy of an element in the \verb=knownEmitterData= master list, we want to ensure that the \verb=data= attribute is never deep-copied. This method implements that operation, such that a deep copy of an \verb=emitter= will contain a deep copy of all its internal data except \verb=data=, which will continue to be a shallow copy of an element in \verb=knownEmitterData=. The optional argument \verb=memo= is the standard dict used by the built-in \verb=copy= module.

This procedure returns nothing.

\subsubsection{\texttt{emitter.\_\_getstate\_\_} and \texttt{emitter.\_\_setstate\_\_}}

Call signatures:

\begin{verbatim}
odict = emitter.__getstate__(self)
\end{verbatim}
and
\begin{verbatim}
emitter.__setstate__(self, idict)
\end{verbatim}

This pair of routines provides the functionality necessary for pickling of \verb=emitter= objects. Custom behavior is required for two reasons. First, the \verb=data= attribute is of class \verb=emitterData=, and \verb=emitterData= objects in turn contain one or more instances of the \verb=collPartner= class. The attribute \verb=collPartner.colRateInterp= is a sequence of callables, and thus cannot be pickled. Second, as with the deep copy operation, we wish to ensure that pickling respects the paradigm that physical data on emitting species is carried in a master dict \verb=knownEmitterData=, all instances of the same emitting species only contain shallow copies of elements of that list.

To implement this functionality, the \verb=emitter.__getstate__= routine returns a dict containing all of the attributes of the \verb=emitter= except \verb=emitter.data=, and with two added entries that store \verb=emitter.data.extrap= and \verb=emitter.data.lamdaFile=. The \verb=emitter.__setstate__= routine takes as an argument a dict (presumably read from a pickle file) containing these two extra attributes. It uses them to re-read the LAMDA file, re-calculate the interpolating functions stored in the instances of \verb=collPartner.colRateInterp=, and re-set the value of \verb=emitter.data.extrap=. It then deletes the two extraneous entries from the dict of the \verb=emitter=.

\subsubsection{\texttt{emitter.setLevPopLTE}}

Call signature:

\begin{verbatim}
emitter.setLevPopLTE(self, temp)
\end{verbatim}

This procedure sets \verb=emitter.levPop= to the values expected for a species in local thermodynamic equilibrium at temperature \verb=temp=. The argument \verb=temp= is a float. The procedure returns nothing.

\subsubsection{\texttt{emitter.setThin}}

Call signature:

\begin{verbatim}
emitter.setThin(self)
\end{verbatim}

This procedure sets all escape probabilities in the array \verb=emitter.escapeProb= to 1.0. It turns nothing.

\subsubsection{\texttt{emitter.setLevPop}}

Call signature:

\begin{verbatim}
infoDict = emitter.setLevPop(self, thisCloud, thin=False, noClump=False, \
                      diagOnly=False, verbose=False)
\end{verbatim}

This procedure calculates the level populations for this emitter in statistical but not necessarily thermodynamic equilibrium, using the stored escape probabilities, and stores them in \verb=emitter.levPop=. The argument \verb=thisCloud= is the \verb=cloud= object for which this computation is to be performed. The optional argument \verb=thin= is a Boolean that, if True, specifies that the escape probabilities for all transitions are to be assumed to be unity for the purposes of this calculation; if it is False, the current value of \verb=emitter.escapeProb= is used instead. The optional argument \verb=noClump=, if True, specifies that the clumping factor should be set to unity; if False, the clumping factor is computed normally from the cloud velocity dispersion and sound speed. The optional argument \verb=verbose=, if True, causes status messages to be printed as the calculation is performed. Finally, the argument \verb=diagOnly= causes the level populations not to be altered, but all the diagnostic information to be computed normally.

In addition to setting the value of \verb=emitter.levPop= and \verb=emitter.levPopInitialized=, this routine returns a dict containing diagnostic information for the computation. The dict contains the following entries: \verb=qNoClump= is a matrix of collisional transition rates between states before a clumping factor is applied, with element $ij$ giving the collision rate for transitions from state $i$ to state $j$; \verb=ngamma= is a matrix of photon occupation numbers from the CMB, with element $ij$ giving the CMB photon occupation number at the frequency corresponding to transitions from state $i$ to state $j$; \verb=inRateCoef= is a matrix giving the total rate coefficient (in s$^{-1}$) for transitions into state $i$ from state $j$, including both radiative and collisional processes; \verb=m= is the matrix that multiplies the vector of level populations in the statistical equilibrium equations (equation 58 of the \despotic\ paper); \verb=levDel= is a list of levels that have been deleted from the computation to reduce the matrix condition number (see Appendix C of the \despotic\ paper), and is included in the dict only if level reduction is required; \verb=inRateCoefRed= and \verb=mRed= are the values of \verb=inRateCoef= and \verb=m= after level reduction.

\subsubsection{\texttt{emitter.setEscapeProb}}

Call signature:

\begin{verbatim}
emitter.setEscapeProb(self, thisCloud, transition=None, \
                          escapeProbGeom='sphere')
\end{verbatim}

This procedure calculates escape probabilities from the currently-stored level populations and stores them in \verb=emitter.escapeProb=. The argument \verb=thisCloud= is a \verb=cloud= object for which this computation is to be performed. The optional argument \verb=transition= may be \verb=None=, or it may be a sequence of two sequences of int. If it is \verb=None=, then escape probabilities are set for all transitions. If it is a sequence of two sequences, then transition[0] is interpreted as a sequence of upper states, and transition[1] as a sequence of lower states; the escape probability is set only for transitions between the specified states. The optional argument \verb=escapeProbGeom= specifies the geometry to be assumed in computing escape probabilities (see Section \ref{sec:escapeprobgeom}). This routine returns nothing.

\subsubsection{\texttt{emitter.setLevPopEscapeProb}}
\label{sec:setlevpopescapeprob}

Call signature:

\begin{verbatim}
success = emitter.setLevPopEscapeProb(self, thisCloud, \
                                escapeProbGeom='sphere', \
                                noClump=False, verbose=False, \
                                reltol=1e-6, abstol=1e-8, \
                                maxiter=200, veryverbose=False, \
                                dampFactor=0.5)
\end{verbatim}

This procedure simultaneously solves for \verb=emitter.levPop= and \verb=emitter.escapeProb= using an iterative procedure, as outlined in the \despotic\ paper. The argument \verb=thisCloud= is the \verb=cloud= object for which this computation is to be performed. The optional argument \verb=escapeProbGeom= gives the geometry to be assumed in the escape probability computation (see Section \ref{sec:escapeprobgeom}). The optional argument \verb=noClump= is a Boolean that, if True, sets the clumping factor to unity. The optional arguments \verb=verbose= and \verb=veryverbose= cause some and a great deal, respectively, of diagnostic information to be printed as the computation proceeds. The optional argument \verb=dampFactor= is a float that gives the damping factor used when iterating. The optional arguments \verb=abstol= and \verb=reltol= give the absolute and relative tolerances used to define the criteria for convergence, as described in the \despotic\ paper. The calculation is considered converged when either the relative or absolute error falls below the specified tolerance. Finally, the optional argument \verb=maxiter= is an int that specifies the maximum number of iterations to perform. The routine returns \verb=True= if either the absolute or relative error falls below the input tolerance before the maximum number of iterations is reached, and False otherwise.

\subsubsection{\texttt{emitter.opticalDepth}}

Call signature:

\begin{verbatim}
tau = opticalDepth(self, transition=None, escapeProbGeom='sphere')
\end{verbatim}

This procedure returns the optical depth corresponding to the escape probabilities \verb=emitter.escapeProb=. The optional argument \verb=transition= may be \verb=None=, or it may be a sequence of two sequences of int. If it is \verb=None=, then optical depths are computed for all transitions in the list of transitions in \verb=emitter.data=. If it is a sequence of two sequences, then transition[0] is interpreted as a sequence of upper states, and transition[1] as a sequence of lower states; the optical depth is computed only for transitions between the specified states. The optional argument \verb=escapeProbGeom= gives the geometry to be assumed in the escape probability computation (see Section \ref{sec:escapeprobgeom}). This procedure returns an array giving the optical depths of the specified transitions.


\subsubsection{\texttt{emitter.luminosityPerH}}

Call signature:
\begin{verbatim}
lum = emitter.luminosityPerH(self, rad, transition=None, total=False, \
                           thin=False)
\end{verbatim}

This procedure returns the luminosity per H nucleus, in erg s$^{-1}$, that is emitted in lines from this species. These quantities are computed from \verb=emitter.levPop= and \verb=emitter.escapeProb=. The argument \verb=rad= is an object of class radiation that describes the radiation field impinging on the cloud. The optional argument \verb=thin= is a Boolean; if True, the escape probability is assumed to be unity for all transitions when performing this computation. The optional argument \verb=transition= may be \verb=None=, or it may be a sequence of two sequences of int. If it is \verb=None=, then luminosities are computed for all transitions in the list of transitions in \verb=emitter.data=. If it is a sequence of two sequences, then transition[0] is interpreted as a sequence of upper states, and transition[1] as a sequence of lower states; the luminosity is computed only for transitions between the specified states.

By default, the routine returns an array giving the luminosity per H nucleus in each line. The optional argument \verb=total= is a Boolean, and, if True, the routine instead returns a single float that is equal to the sum of the luminosities of all transitions.

\subsubsection{\texttt{emitter.setExtrap}}

Call signature:

\begin{verbatim}
emitter.setExtrap(self, extrap)
\end{verbatim}

This procedure changes whether extrapolation is allowed for this species; the value of \verb=emitter.data.extrap= is set equal to the value of the argument \verb=extrap=. This procedure returns nothing.


\clearpage

\subsection{emitterData}
\label{sec:emitterData}

The \verb=emitterData= module defines the \verb=emitterData= class, which stores physical data on emitting species. One instance of the \verb=emitterData= class is created each time a distinct emitting species is created. The non-callable attributes of \verb=emitterData= objects are listed in Table \ref{tab:emitterData}. The callable attributes are listed below.

\begin{table}
\begin{center}
\begin{tabular}{lll}
\hline\hline
Name & Type & Meaning \\
\hline\hline
\texttt{name} & string & Name of emitting species \\
\texttt{lamdaFile} & string & Name of the file from which the data for this \\
& & \quad species was read \\
\texttt{molWgt} & float & Molecular weight of species in units of $m_{\rm H}$ \\
\texttt{nlev} & int & Number of energy levels for \\
& & \quad this species \\
\texttt{levEnergy} & array(nlev) of float & Energies of levels (in erg) \\
\texttt{levTemp} & array(nlev) of float & Energies of levels (in K) \\
\texttt{nrad} & int & Number of radiative transitions for this species \\
\texttt{radUpper} & array(nrad) of int & Upper levels of radiative transitions \\
\texttt{radLower} & array(nrad) of int & Lower levels of radiative transitions \\
\texttt{radFreq} & array(nrad) of float & Frequencies of radiative transitions (in Hz) \\
\texttt{radTemp} & array(nrad) of float & Energy differences of radiative transitions \\
& & \quad (in K) \\
\texttt{radTUpper} & array(nrad) of float & Energies of radiative transition upper \\
& & \quad levels (in K) \\
\texttt{radA} & array(nrad) of float & Einstein $A$ coefficients of radiative transitions\\
\texttt{partners} & dict & Dict of collision partners; keys are partner \\
& & \quad names, values are of class \texttt{collPartner} \\
\texttt{EinsteinA} & array(nlev, nlev) of float & Matrix of Einstein $A$ values connecting every \\
& & \quad pair of states\\
\texttt{freq} & array(nlev, nlev) of float & Matrix of frequencies for transitions connecting \\
& & \quad every pair of states\\
\texttt{dT} & array(nlev, nlev) of float & Matrix of energy differences between\\
& & \quad every pair of states (in K) \\
\texttt{wgtRatio} & array(nlev, nlev) of float & Matrix of ratios of statistical weights for every \\
& & \quad pair of states \\
\texttt{extrap} & Boolean & Can collision rates for this species be\\
& & \quad extrapolated? \\
\hline
\end{tabular}
\caption{
\label{tab:emitterData}
Non-callable attributes of the \texttt{emitterData} class.
}
\end{center}
\end{table}

\subsubsection{\texttt{emitterData.\_\_init\_\_}}

Call signature:

\begin{verbatim}
emitterData.__init__(self, emitName, emitterFile=None, emitterURL=None, \
                     extrap=False, noRefresh=False)
\end{verbatim}

This routine initializes \verb=emitterData= objects. The optional arguments \verb=emitterFile=, \verb=emitterURL=, and \verb=extrap= are identical to the arguments of the same name for the \verb=cloud.addEmitter= routine (see Section \ref{sec:cloud.addEmitter}). The \verb=noRefresh= optional argument is a Boolean. If it is False, before reading data from a file stored locally, the routine will check the age of the file. If it is older than six months, the routine will attempt to download a new copy of the data from LAMDA. If \verb=noRefresh= is True, this behavior is suppressed and no new data will be downloaded regardless of the age of the file.

This routine returns nothing.

\subsubsection{\texttt{emitterData.collRateMatrix}}

Call signature:

\begin{verbatim}
rate = emitterData.collRateMatrix(self, nH, comp, temp)
\end{verbatim}

This routine returns the rate of collisional transitions between every pair of levels. The argument \verb=nH= is the volume density of H nuclei in cm$^{-3}$. The argument \verb=comp= is an object of class composition (see Section \ref{sec:comp}) that describes the gas bulk chemical composition. The argument \verb=temp= is a float that gives the gas kinetic temperature. The routine returns an array \verb=rate= of shape (\verb=nlev=, \verb=nlev=) in which element $ij$ gives the rate of collisional transitions from state $i$ to state $j$ in units of s$^{-1}$, not including any enhancement due to clumping.


\subsubsection{\texttt{emitterData.partFunc}}

Call signature:

\begin{verbatim}
Z = emitterData.partFunc(self, temp)
\end{verbatim}

This routine computes the partition function $Z(T)$ for the species. The argument \verb=temp= is a temperature, can be either a float or an array of floats. The return value \verb=Z= gives the partition function, and is either a float or an array of floats of the same shape as the input temperature array.

\clearpage

\subsection{collPartner}
\label{sec:collPatner}

The \verb=collPartner= module defines the \verb=collPartner= class, a class that stores information about collision partners for emitting species. Instances of \verb=collPartner= are created when instances of \verb=emitterData= are created, and the corresponding LAMDA files are read. The non-callable attributes of a \verb=collPartner= object are listed in Table \ref{tab:collPartner}. The callable attributes of the class are listed in the following sections.

\begin{table}
\begin{center}
\begin{tabular}{lll}
\hline\hline
Name & Type & Meaning \\
\hline\hline
\texttt{nlev} & int & Number of energy levels for the emitting \\
& & \quad species \\
\texttt{ntrans} & int & Number of collisional transitions in the\\
& & \quad data table \\
\texttt{ntemp} & int & Number of temperatures in the data\\
& & \quad table\\
\texttt{tempTable} & array(ntemp) of float & Array of temperatures at which collision\\
& & \quad rate coefficients are tabulated \\
\texttt{colUpper} & array(ntrans) of int & Array of upper states for collisional \\
& & \quad transitions\\
\texttt{colLower} & array(ntrans) of int & Array of lower states for collisional\\
& & \quad transitions\\
\texttt{colRate} & array(ntrans, ntemp) of float & Table of downward transition rate \\
& & \quad coefficients\\
\texttt{colRateInterp} & sequence(ntrans) of functions & Functions giving the rate coefficient for \\
& & \quad each transition interpolated in \\
& & \quad temperature \\
\hline
\end{tabular}
\caption{
\label{tab:collPartner}
Non-callable attributes of the \texttt{collPartner} class.
}
\end{center}
\end{table}

\subsubsection{\texttt{collPartner.\_\_init\_\_}}

Call signature:

\begin{verbatim}
collPartner.__init__(self, fp, nlev, extrap=False)
\end{verbatim}

This method initializes a \verb=collPartner= object. The argument \verb=fp= is a file object, and it must point to the section of a LAMDA-formatted file at which the information about a particular collision partner beings. The argument \verb=nlev= is an integer that gives the number of levels in the emitter for which this is a collision partner. The optional argument \verb=extrap= is a Boolean that specifies whether extrapolation is allowed for this emitter. If \verb=False=, no extrapolation in temperature outside the range found in the LAMDA data table will be allowed; if \verb=True=, extrapolation will be performed, assuming the rate coefficient is a powerlaw in temperature. This function returns nothing.

When this function is called, data on this collision partner is read from the LAMDA-formatted file pointed to by \verb=fp=, and \verb=fp= is advanced to the next collision partner, or to file end if this is the last collision partner listed. The routine initializes the sequence of interpolating functions \verb=colRateInterp=, so that, after this function returns, \verb=colRateInterp[n]= is a function that takes as an argument the natural log of the temperature, and returns the collision rate coefficient at that temperature, as determined by linearly interpolating in log temperature on the input data table.

\subsubsection{\texttt{collPartner.colRateMatrix}}
\label{sec:colratematrix}

Call signature:

\begin{verbatim}
k = collPartner.colRateMatrix(self, temp, levWgt, levTemp)
\end{verbatim}

This routine calculates collision rate coefficients between levels by interpolating on the stored data table. The argument \verb=temp= is a float that gives the gas kinetic temperature in K, the argument \verb=levWgt= is an array giving the statistical weights of the levels, and \verb=levTemp= is an array giving the energies of the levels (measured in K). The routine returns a matrix of size \verb=nlev= $\times$ \verb=nlev= that contains the collision rate coefficient for transitions between states at the specified gas temperature. Element $ij$ of the matrix is the rate coefficient from state $i$ to state $j$. 


\subsubsection{\texttt{collPartner.colRates}}
\label{sec:colrates}

Call signature:

\begin{verbatim}
rates = colRates(self, temp, transition=None)
\end{verbatim}

This routine calculates collision rate coefficients by interpolating on the stored data table. The argument \verb=temp= is a float or an array of floats that gives the gas kinetic temperature in K. The optional argument \verb=transition= specifies which transitions are to be computed. If it is \verb=None=, then the rates for all transitions are computed; if it is an array of integers of shape $(2,N)$ then elements $(0,i)$ and $(1,i)$ are interpreted as the identifying the lower and upper levels of the transition(s) whose rate coefficients are to be computed. The return value \verb=rates= is an array of interpolated collision rate coefficients. If \verb=temp= is a float then it is an array of shape $N$, where $N$ is the number of transitions that have been computed; if \verb=temp= is an array of floats, then \verb=rates= is of shape $(N, \verb=len(temp)=)$.

\clearpage

\subsection{lineProfLTE}
\label{sec:lineproflte}

The \verb=lineProfLTE= module provides the routine \verb=lineProfLTE=, which is capable of computing the brightness temperature as a function of velocity for clouds in LTE. The call signature is:

\begin{verbatim}
TB, v = lineProfLTE(emdat, u, l, R, denProf, TProf, \
                    vProf=0.0, sigmaProf=0.0, \
                    offset=0.0, TCMB=2.73, vOut=None, vLim=None, \
                    nOut=100, dv=None, mxstep=10000)
\end{verbatim}

The first argument \verb=emdat= is an object of class \verb=emitterData=, which gives the data for the emitter whose line is to be computed. The arguments \verb=u= and \verb=l= are integers giving the upper and lower quantum state for the line whose profiles is to be computed. The argument \verb=R= is the cloud radius in cm. The arguments \verb=denProf=, \verb=TProf=, \verb=vProf=, and \verb=sigmaProf= are all either floats or callables. If they are floats, they specify the constant value of the number density of emitting molecules, gas kinetic temperature, bulk radial velocity, and non-thermal velocity dispersion within the cloud, in CGS units. If they are callables, they must accept as an argument a single float in the range $0-1$, which gives the radial position normalized to the cloud radius \verb=R=. They must return a single float that gives the number density of emitters, gas kinetic temperature, bulk radial velocity, or non-thermal velocity dispersion at that radius, again in CGS units.

The optional argument \verb=offset= is a float in the range $0-1$ that specifies the offset of the line of sight from the cloud's projected center, normalized to the cloud radius. The optional argument \verb=TCMB= gives the cosmic microwave background temperature.

The optional arguments \verb=vOut=, \verb=vLim=, \verb=nOut=, and \verb=dv= provide mechanisms to control the velocities at which the brightness temperature of the line is computed. Here \verb=vOut= is a sequence that specifies the exact velocities at which the computation should be performed, \verb=vLim= gives minimum and maximum velocities for the computation, \verb=nOut= specifies the number of velocities at which to output, evenly spaced between \verb=vLim[0]= and \verb=vLim[1]=, and \verb=dv= specifies the spacing in velocity between outputs. Setting more than the minimum number of these parameters required to specify a set of velocities will produce unpredictable behavior. If \verb=vLim= and \verb=vOut= are both \verb=None=, the velocity range over which the computation is performed is from $-5\sigma_{\rm tot}(R) -|v(R)|$ to $5\sigma_{\rm tot}(R)+ |v(R)|$, where $\sigma_{\rm tot}$ is the total velocity dispersion including both thermal and non-thermal contributions, and $v$ is the bulk velocity. All quantities are in CGS units.

Finally, the optional argument \verb=mxstep= gives the maximum number of steps to allow in the ODE integrator before returning with an error. The default value is sufficient for most computations, but clouds with exceptionally rapidly-varying profiles of one or more quantities may require larger values.

The function returns two arrays \verb=TB= and \verb=v=. The latter gives the velocities at which the brightness temperature has been computed (in cm s$^{-1}$), and the former gives the brightness temperature at those velocities (in K).

\clearpage

\subsection{fetchLamda}
\label{sec:fetchlambda}

The \verb=fetchLamda= module provides the routine \verb=fetchLamda=, a utility for downloading Leiden Atomic and Molecular Database (LAMDA) files. The call signature is:

\begin{verbatim}
fname = fetchLamda(inputURL, path=None, fileName=None)
\end{verbatim}

When this function is run, it downloads a single file and stores it locally. The argument \verb=inputURL= is a string that specifies the file to be downloaded. It may either be an absolute URL, beginning with ``http://", or a relative URL. If it is a relative URL, then the absolute URL is constructed by prepending \verb=$DESPOTIC_LAMDAURL/datafiles/=, where \verb=$DESPOTIC_LAMDAURL= is an environment variable, or\\
\verb=http://home.strw.leidenuniv.nl/~moldata/datafiles/= if the environment variable is not set. The optional argument \verb=path= is a string giving a relative or absolute path where the downloaded file is to be stored. If it is \verb=None=, the file is stored in the current working directory. If the specified path does not exist, it is created. Finally, the optional argument \verb=fileName= is the name to give to the file. If it is \verb=None=, then the local file name will be the same as the name of the file that is downloaded.

This routine returns the name of the file created if it succeeds, or \verb=None= if the download is unsuccessful. Note that failed downloads or writes of files do not raise errors, they simply cause \verb=None= to be returned.

\clearpage

\subsection{refreshLamda}
\label{sec:refreshLamda}

The \verb=refreshLamda= module provides the routine \verb=refreshLamda=, a utility for manually updating the local cache of the Leiden Atomic and Molecular Database (LAMDA). The call signature is:

\begin{verbatim}
refreshLamda(path=None, cutoffDate=None, cutoffAge=None, LamdaURL=None)
\end{verbatim}                     

By default this routine examines every file in the directory \verb=$DESPOTIC_HOME/LAMDA=, where \verb=$DESPOTIC_HOME= is an environment variable; if this environment variable is unset, it checks the directory \verb=LAMDA= relative to the current working directory. The optional argument \verb=path= is a string that specifies the path where files are located, and overrides these defaults it is set to something other than \verb=None=. For each file in the target directory, it checks the date of last modification, flagging those files that are older than a specified age or cutoff date. By default files older than 6 months are flagged, but the user can manually specify a different cutoff age or date using the optional arguments \verb=cutoffAge= or \verb=cutoffDate=; cutoff ages must be objects of the class \verb=datetime.timedelta=, and cutoff dates must be objects of the class \verb=datetime.datetime or \verb=datetime.date=. If any files are flagged, the routine then attempts to download a replacement for that file using the \verb=fetchLamda= routine (see Section \ref{sec:fetchlambda}). It searches for the replacement at a URL given by \verb=LamdaURL= if that optional argument is set to a string, or at the default location searched by \verb=refreshLamda= if it is \verb=None=.

This procedure returns nothing.

\clearpage

\subsection{chemEvol}
\label{sec:chemevol}

\clearpage

\subsection{setChemEq}
\label{sec:setchemeq}

\clearpage

\subsection{chemNetwork}
\label{sec:chemnetwork}

\clearpage

\subsection{NL99}
\label{sec:nl99}

\clearpage

\subsection{shielding}
\label{sec:shielding}

\clearpage

\subsection{abundanceDict}
\label{sec:abundancedict}

The \verb=abundanceDict= module defines the \verb=abundanceDict= class, a class that provides a dict-like interface to chemical abundances. An instance of this class is created via the method \verb=abundanceDict.__init__(self, specList, x)= where \verb=specList= is a list of strings giving the names of all the species, and \verb=x= is a numPy array of rank $>=1$ whose first dimension must be of the same size as the number of elements in \verb=specList=. 

Once instantiated, \verb=abundanceDict= behaves exactly as would a dict whose keys are \verb=specList= and whose corresponding values are the elements of \verb=x=; all the methods available for dict are available for \verb=abundanceDict=, including \verb=__getitem__=, \verb=__setitem__=, \verb=__iter__=, \verb=__len__=, \verb=__contains__=, \verb=keys=, \verb=values=, \verb=has_key=, and \verb=copy=. In addition, \verb=abundanceDict= defines a \verb=__repr__= method that provides a nicely-formatted printed version of the information. The only difference from a standard dict is that the list of keys is immutable once the \verb=abundanceDict= is instantiated, so that the dict methods \verb=__delitem__=, \verb=clear=, \verb=pop=, \verb=popitem=, and \verb=update= are all disallowed, as is the use of \verb=__setitem__= with any key that does not match one of the keys in the \verb=abundanceDict= at the time it was instantiated.

\clearpage

\section{Revision History}

\begin{enumerate}
\item Version 1.1.0, 5/2013 -- added chemistry capabilities; also numerous minor bug fixes
\item Version 1.0.4, 4/2013 -- fixed a bug with reading LAMDA files, added \verb|XH2| and \verb|H2OPR| as \verb|cloud| properties
\item Version 1.0.3, 4/2013 -- fixed a bug introduced in version 1.0.2; also added section on dependencies to the manual; no functional changes
\item Version 1.0.2, 4/2013 -- revised the way residuals are calculated in \verb=cloud.setTempEq=, \verb=cloud.setDustTempEq=, and \verb=cloud.setGasTempEq= to provide a higher probability of convergence when the initial guess is very far from the correct answer.
\item Version 1.0.1, 4/2013 -- added license statements to all source files.
\item Version 1.0, 4/2013 -- initial release
\end{enumerate}

\end{document}
